Skip to content

perf(hex): decode 16-byte blocks with NEON and SSE2 - #20

Open
hood wants to merge 6 commits into
nodejs:mainfrom
hood:perf/hex-decode-simd
Open

hood wants to merge 6 commits into
nodejs:mainfrom
hood:perf/hex-decode-simd

Conversation

@hood

@hood hood commented Nov 9, 2026

Copy link
Copy Markdown

Fixes #19

Decodes hex in 16-byte output blocks with NEON on arm64 and SSE2 on x86-64.
In node, at least by my measurements 🤞, this makes Buffer.from(hex)
3.3x faster at 1 KiB and buf.write(str, 'hex') 3.9x faster at 2 KiB,
with byte-identical output .

How

  • HexDecode<T> with a one-byte T first calls the new out-of-line
    HexDecodeBlocks(), then the existing scalar loop continues from where it
    stopped. Intrinsics stay out of the public header.
  • Each block loads 32 chars and converts digits and both letter cases to
    nibbles with arithmetic, then validates them with one single horizontal check:
    vminvq_u8 on NEON, _mm_movemask_epi8 on SSE2.
  • A block with any invalid char is not written. The scalar loop resumes at that
    block and returns at the exact invalid pair, so we ensure that truncation
    semantics are unchanged.
  • SSE2 avoids SSSE3: unsigned compares use _mm_min_epu8, and nibble pairs are
    combined with 16-bit shifts and _mm_packus_epi16.
  • Without NEON or SSE2, HexDecodeBlocks() returns 0 and decoding is fully
    scalar, as before.
  • Two-byte input is untouched.

Results

Library (nbytes::HexDecode, one-byte input, out-of-line, median of 9
batches × 2 interleaved runs, M1 Pro, -O3):

Bytes main arm64 PR arm64 Speedup main x86-64* PR x86-64* Speedup
16 11.2 ns 3.3 ns 3.4x 15.9 ns 5.1 ns 3.1x
32 22.0 ns 5.5 ns 4.0x 33.5 ns 7.9 ns 4.2x
256 186 ns 34 ns 5.5x 258 ns 51 ns 5.1x
1024 713 ns 133 ns 5.4x 1023 ns 195 ns 5.3x
16384 11.3 µs 2.1 µs 5.5x 16.6 µs 3.1 µs 5.4x

* x86-64 build run under Rosetta 2. Treat the absolute numbers as indicative;
the ratios hold.

Node.js (main at 768315cf with this patch applied to deps/nbytes,
benchmark/compare.js --runs 20, Welch t-test):

Benchmark main PR Change
buffers/buffer-hex-encode.js len=64 (this benchmark measures Buffer.from(hex)) 7.00M ops/s 10.16M ops/s +41.8% ***
buffers/buffer-hex-encode.js len=1024 1.20M 3.87M +229.9% ***
buffers/buffer-write-string.js len=2048 encoding=hex 1.37M 5.24M +294.2% ***
... args=offset 2.47M 7.91M +233.5% ***
... args=offset+length 1.36M 5.24M +278.0% ***
buffers/buffer-write-string-short.js encoding=hex len=1/8/16 −1.4 to −2.4%, not significant (p ≥ 0.42)

Testing

  • New tests in tests/basic.cpp compare against an independent reference
    decoder:
    • every byte value 0–255 at every position of a 96-char input (spans several
      blocks);
    • random lower and upper case data for every length 0–160;
    • output buffers shorter than the input, and odd source lengths.
  • ctest passes 11/11 on arm64 (NEON) and x86-64 (SSE2,
    -DCMAKE_OSX_ARCHITECTURES=x86_64).
  • Mutation check: disabling the validity check in either SIMD path makes the
    new tests fail.
  • Node.js built with the patch:
    • a 40k-case differential fuzz of Buffer.from(hex) / buf.write(hex)
      matches main exactly (invalid bytes, two-byte strings, offsets, odd
      lengths);
    • test/parallel passes, except test-node-run and test-snapshot-warning,
      which fail the same way on unpatched main in my environment.
  • Formatted with clang-format at version 17.

Repro (library):

cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build && ctest --test-dir build

Repro (Node.js, with the patch in deps/nbytes):

node benchmark/compare.js --old ./node-main --new ./node-pr --runs 20 --filter buffer-hex-encode buffers
node benchmark/compare.js --old ./node-main --new ./node-pr --runs 20 --filter buffer-write-string --set encoding=hex buffers

@aduh95

aduh95 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

I've asked a coding agent to review the diff:


I reviewed the diff and found one blocking issue: the NEON path doesn't compile on 32-bit ARM with NEON enabled. The rest of the logic looks correct. The CI only covers macOS arm64, Linux x64 and Windows x64, so it can't catch this.

Blocking: armv7 + NEON build failure
__ARM_NEON is also defined on 32-bit ARM when NEON is on (e.g. -mfpu=neon, Cortex-A7). vminvq_u8 only exists on AArch64. I applied the diff to a fresh nbytes clone and compiled it with zig's bundled clang for -target arm-linux-gnueabihf -mcpu=cortex_a7:

src/nbytes.cpp:184:7: error: use of undeclared identifier 'vminvq_u8'

Because Node.js vendors nbytes, this would break Node.js' armv7 builds that have NEON enabled. I haven't checked which official or distro armv7 configs actually turn NEON on.

The simplest fix is to only take the NEON path on 64-bit:

#if defined(__aarch64__) || defined(_M_ARM64)

Alternatively, keep armv7 NEON and replace the vminvq_u8 check with a 64-bit lane test, e.g. vget_lane_u64(vreinterpret_u64_u8(vand_u8(vget_low_u8(valid), vget_high_u8(valid))), 0) == ~0ULL.

I ran the x86 and aarch64 syntax checks too, but they were inconclusive: zig failed with a cache-rename error before reporting anything about the source.

Non-blocking
  • Call overhead on short inputs: every one-byte HexDecode now makes a call into another file (it can't be inlined), even for short inputs. Skipping it in the header when srcLen < 32 would avoid a small slowdown on short hex strings. That matters for Node.js, which decodes a lot of short hex.
  • Public header: HexDecodeBlocks becomes a public symbol in nbytes.h. Consider putting it in an internal namespace so it isn't part of the API.
  • Hidden include: std::min in nbytes.cpp only works because nbytes.h happens to include <algorithm>. Including it directly would be cleaner.
  • No benchmark numbers: the diff doesn't include any. It's worth asking for, including the short-input case.
  • Test gap: CI has no 32-bit ARM or ARM64 Windows job, which is how the blocking issue got through. Consider adding a cross-compile check.

@hood

hood commented Nov 16, 2026 •

Copy link
Copy Markdown
Author

alright, makes sense, i completely overlooked the armv7 thing. Thanks for running it @aduh95!

armv7 + NEON (blocking): fixed in d0915f8. NEON now only kicks in on __aarch64__ / _M_ARM64, so armv7 just keeps the scalar path it has today. Cross-compiled with zig 0.17.1, all clean:

target path
arm-linux-gnueabihf -mcpu=cortex_a7 (the failing one) scalar
arm-linux-gnueabihf scalar
aarch64-linux-gnu, aarch64-windows-gnu NEON
x86_64-linux-gnu, x86-linux-gnu, x86_64-windows-gnu SSE2

Short inputs: fair point, 6ffc50b skips the call entirely when len < 16 || srcLen < 32. nbytes::HexDecode one-byte input, M1 Pro, median of 9 interleaved rounds:

bytes main before now now vs main
1 1.1 ns 2.0 ns 1.6 ns +0.5 ns
4 3.2 ns 4.1 ns 3.6 ns +0.4 ns
8 5.9 ns 6.8 ns 6.5 ns +0.6 ns
15 10.8 ns 11.7 ns 11.3 ns +0.5 ns
16 11.4 ns 3.2 ns 3.5 ns 3.3x faster
32 22.5 ns 5.5 ns 5.5 ns 4.1x faster
1024 741.5 ns 133.3 ns 131.9 ns 5.6x faster

The leftover ~0.5 ns below 16 bytes is most likely the extra length check, kinda nothing next to the ~100 ns a Buffer.from(hex) call costs in node. Even the "before" version didn't show up in node's buffer-write-string-short.js (len 1/8/16 came out at -1.4% to -2.4%, p ≥ 0.42).

Public header: moved to nbytes::detail::HexDecodeBlocks (6ffc50b).

<algorithm>: included directly now (249e15d).

Benchmarks: the lib and node compare.js numbers are in the PR description, the short-input ones are above.

CI for armv7 / Windows ARM64: agree it's deffo a gap. I'd rather do it in a follow-up PR (cross-compile job, maybe qemu for armv7) so this one stays focused, if that works for you. Otherwise just lmk and i'll do it here, it's my first time contributing to this project so I'll gladly adapt to anything 😄.

@hood
hood requested a review from ronag November 17, 2026 12:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

HexDecode is scalar: Buffer.from(hex) ~5x slower than base64 decode

3 participants